home *** CD-ROM | disk | FTP | other *** search
/ Light ROM 1 / LIGHT-ROM 1 (Amiga Library Services)(1994).iso / ffdisks / d982.lha / HWGRCS / HWGpatchP1_2_1.lha / patch-2.1 / doc / patch.doc
Text File  |  1993-12-04  |  20KB  |  513 lines
  1.  
  2.  
  3.  
  4. PATCH(1)                                                 PATCH(1)
  5.  
  6.  
  7. NAME
  8.        patch - apply a diff file to an original
  9.  
  10. SYNOPSIS
  11.        patch [options] [origfile [patchfile]] [+ [options] [orig­
  12.        file]]...
  13.  
  14.        but usually just
  15.  
  16.        patch <patchfile
  17.  
  18. DESCRIPTION
  19.        Patch will take a patch file containing any  of  the  four
  20.        forms  of  difference listing produced by the diff program
  21.        and apply those differences to an original file, producing
  22.        a patched version.  By default, the patched version is put
  23.        in place of the original, with the original file backed up
  24.        to  the  same name with the extension ".orig" ("~" on sys­
  25.        tems that do not support long file names), or as specified
  26.        by  the  -b  (--suffix),  -B  (--prefix),  or  -V  (--ver­
  27.        sion-control) options.   The  extension  used  for  making
  28.        backup   files   may   also   be  specified  in  the  SIM­
  29.        PLE_BACKUP_SUFFIX environment variable, which is  overrid­
  30.        den by the above options.
  31.  
  32.        If  the  backup  file  already exists, patch creates a new
  33.        backup file name by changing the first lowercase letter in
  34.        the  last component of the file's name into uppercase.  If
  35.        there are no  more  lowercase  letters  in  the  name,  it
  36.        removes  the  first  character  from the name.  It repeats
  37.        this process until it comes up with  a  backup  file  that
  38.        does not already exist.
  39.  
  40.        You  may also specify where you want the output to go with
  41.        a -o (--output) option; if that file already exists, it is
  42.        backed up first.
  43.  
  44.        If patchfile is omitted, or is a hyphen, the patch will be
  45.        read from standard input.
  46.  
  47.        Upon startup, patch will attempt to determine the type  of
  48.        the  diff  listing, unless over-ruled by a -c (--context),
  49.        -e (--ed), -n (--normal), or -u (--unified) option.   Con­
  50.        text  diffs (old-style, new-style, and unified) and normal
  51.        diffs are applied by the patch program  itself,  while  ed
  52.        diffs are simply fed to the ed editor via a pipe.
  53.  
  54.        Patch  will  try  to  skip  any leading garbage, apply the
  55.        diff, and then skip any trailing garbage.  Thus you  could
  56.        feed  an  article  or message containing a diff listing to
  57.        patch, and it should work.  If the entire diff is indented
  58.        by a consistent amount, this will be taken into account.
  59.  
  60.        With  context  diffs,  and  to a lesser extent with normal
  61.  
  62.  
  63.  
  64.                               LOCAL                             1
  65.  
  66.  
  67.  
  68. PATCH(1)                                                 PATCH(1)
  69.  
  70.  
  71.        diffs, patch can detect when the line numbers mentioned in
  72.        the patch are incorrect, and will attempt to find the cor­
  73.        rect place to apply each hunk of the patch.   As  a  first
  74.        guess,  it  takes  the line number mentioned for the hunk,
  75.        plus or minus any offset used  in  applying  the  previous
  76.        hunk.   If  that is not the correct place, patch will scan
  77.        both forwards and backwards for a set  of  lines  matching
  78.        the  context  given  in the hunk.  First patch looks for a
  79.        place where all lines of the context match.   If  no  such
  80.        place  is  found, and it's a context diff, and the maximum
  81.        fuzz factor is set to 1 or more, then another  scan  takes
  82.        place  ignoring  the  first  and last line of context.  If
  83.        that fails, and the maximum fuzz factor is  set  to  2  or
  84.        more,  the  first  two  and  last two lines of context are
  85.        ignored, and another scan is made.  (The  default  maximum
  86.        fuzz  factor  is  2.)   If  patch  cannot  find a place to
  87.        install that hunk of the patch, it will put the  hunk  out
  88.        to a reject file, which normally is the name of the output
  89.        file plus ".rej" ("#" on systems that do not support  long
  90.        file  names).   (Note that the rejected hunk will come out
  91.        in context diff form whether the input patch was a context
  92.        diff  or  a  normal diff.  If the input was a normal diff,
  93.        many of the contexts will simply be null.)  The line  num­
  94.        bers on the hunks in the reject file may be different than
  95.        in the patch file: they reflect the  approximate  location
  96.        patch  thinks  the  failed  hunks  belong  in the new file
  97.        rather than the old one.
  98.  
  99.        As each hunk is completed, you will be  told  whether  the
  100.        hunk succeeded or failed, and which line (in the new file)
  101.        patch thought the hunk should go on.  If this is different
  102.        from  the  line  number  specified in the diff you will be
  103.        told the offset.  A single large offset MAY be an  indica­
  104.        tion  that  a  hunk was installed in the wrong place.  You
  105.        will also be told if a fuzz factor was used  to  make  the
  106.        match,  in  which  case you should also be slightly suspi­
  107.        cious.
  108.  
  109.        If no original file is  specified  on  the  command  line,
  110.        patch will try to figure out from the leading garbage what
  111.        the name of the file to edit is.  In the header of a  con­
  112.        text  diff,  the  file  name is found from lines beginning
  113.        with "***" or "---", with the shortest name of an existing
  114.        file  winning.   Only  context diffs have lines like that,
  115.        but if there is an "Index:" line in the  leading  garbage,
  116.        patch  will  try to use the file name from that line.  The
  117.        context diff header takes precedence over an  Index  line.
  118.        If  no file name can be intuited from the leading garbage,
  119.        you will be asked for the name of the file to patch.
  120.  
  121.        If the original file cannot be found or is read-only,  but
  122.        a  suitable  SCCS or RCS file is handy, patch will attempt
  123.        to get or check out the file.
  124.  
  125.  
  126.  
  127.  
  128.                               LOCAL                             2
  129.  
  130.  
  131.  
  132. PATCH(1)                                                 PATCH(1)
  133.  
  134.  
  135.        Additionally, if the leading garbage contains a "Prereq: "
  136.        line,  patch  will  take the first word from the prerequi­
  137.        sites line (normally a version number) and check the input
  138.        file to see if that word can be found.  If not, patch will
  139.        ask for confirmation before proceeding.
  140.  
  141.        The upshot of all this is that you should be able to  say,
  142.        while in a news interface, the following:
  143.  
  144.             | patch -d /usr/src/local/blurfl
  145.  
  146.        and patch a file in the blurfl directory directly from the
  147.        article containing the patch.
  148.  
  149.        If the patch file contains more than one patch, patch will
  150.        try  to  apply  each of them as if they came from separate
  151.        patch files.  This means, among other things, that  it  is
  152.        assumed  that the name of the file to patch must be deter­
  153.        mined for each diff listing, and that the  garbage  before
  154.        each  diff listing will be examined for interesting things
  155.        such as file names and revision level, as mentioned previ­
  156.        ously.   You  can  give options (and another original file
  157.        name) for the second and subsequent patches by  separating
  158.        the  corresponding argument lists by a '+'.  (The argument
  159.        list for a second or subsequent patch may  not  specify  a
  160.        new patch file, however.)
  161.  
  162.        Patch recognizes the following options:
  163.  
  164.        -b suff, --suffix=suff
  165.             causes  suff  to  be interpreted as the backup exten­
  166.             sion, to be used in place of ".orig" or "~".
  167.  
  168.        -B pref, --prefix=pref
  169.             causes pref to be interpreted  as  a  prefix  to  the
  170.             backup  file name. If this argument is specified, any
  171.             argument from -b will be ignored.
  172.  
  173.        -c, --context
  174.             forces patch to interpret the patch file as a context
  175.             diff.
  176.  
  177.        -d dir, --directory=dir
  178.             causes  patch to interpret dir as a directory, and cd
  179.             to it before doing anything else.
  180.  
  181.        -D sym, --ifdef=sym
  182.             causes patch to use the  "#ifdef...#endif"  construct
  183.             to mark changes.  sym will be used as the differenti­
  184.             ating symbol.
  185.  
  186.        -e, --ed
  187.             forces patch to interpret the patch  file  as  an  ed
  188.             script.
  189.  
  190.  
  191.  
  192.                               LOCAL                             3
  193.  
  194.  
  195.  
  196. PATCH(1)                                                 PATCH(1)
  197.  
  198.  
  199.        -E, --remove-empty-files
  200.             causes  patch  to  remove output files that are empty
  201.             after the patches have been applied.
  202.  
  203.        -f, --force
  204.             forces patch to assume that the  user  knows  exactly
  205.             what  he  or  she  is doing, and to not ask any ques­
  206.             tions.  It assumes the following:  skip  patches  for
  207.             which  a  file  to  patch can't be found; patch files
  208.             even though they  have  the  wrong  version  for  the
  209.             ``Prereq:''  line  in  the  patch;  and  assume  that
  210.             patches are not reversed even if they look like  they
  211.             are.   This  option does not suppress commentary; use
  212.             -s for that.
  213.  
  214.        -t, --batch
  215.             similar to -f, in that it suppresses  questions,  but
  216.             makes  some  different  assumptions: skip patches for
  217.             which a file to patch can't be  found  (the  same  as
  218.             -f);  skip  patches  for which the file has the wrong
  219.             version for the ``Prereq:'' line in  the  patch;  and
  220.             assume  that  patches  are reversed if they look like
  221.             they are.
  222.  
  223.        -F number, --fuzz=number
  224.             sets the  maximum  fuzz  factor.   This  option  only
  225.             applies  to context diffs, and causes patch to ignore
  226.             up to that  many  lines  in  looking  for  places  to
  227.             install  a  hunk.   Note  that  a  larger fuzz factor
  228.             increases the odds of a faulty  patch.   The  default
  229.             fuzz  factor is 2, and it may not be set to more than
  230.             the number of lines of context in the  context  diff,
  231.             ordinarily 3.
  232.  
  233.        -l, --ignore-whitespace
  234.             causes  the  pattern  matching to be done loosely, in
  235.             case the tabs and spaces have  been  munged  in  your
  236.             input  file.   Any sequence of whitespace in the pat­
  237.             tern line will match any sequence in the input  file.
  238.             Normal  characters  must  still  match exactly.  Each
  239.             line of the context must still match a  line  in  the
  240.             input file.
  241.  
  242.        -n, --normal
  243.             forces  patch to interpret the patch file as a normal
  244.             diff.
  245.  
  246.        -N, --forward
  247.             causes patch to ignore patches  that  it  thinks  are
  248.             reversed or already applied.  See also -R .
  249.  
  250.        -o file, --output=file
  251.             causes  file  to  be  interpreted  as the output file
  252.             name.
  253.  
  254.  
  255.  
  256.                               LOCAL                             4
  257.  
  258.  
  259.  
  260. PATCH(1)                                                 PATCH(1)
  261.  
  262.  
  263.        -p[number], --strip[=number]
  264.             sets the pathname strip  count,  which  controls  how
  265.             pathnames  found  in  the  patch file are treated, in
  266.             case the you keep your files in a different directory
  267.             than  the  person  who sent out the patch.  The strip
  268.             count specifies how many slashes are to  be  stripped
  269.             from  the  front  of  the pathname.  (Any intervening
  270.             directory names also go away.)  For example,  suppos­
  271.             ing the file name in the patch file was
  272.  
  273.                  /u/howard/src/blurfl/blurfl.c
  274.  
  275.             setting  -p  or -p0 gives the entire pathname unmodi­
  276.             fied, -p1 gives
  277.  
  278.                  u/howard/src/blurfl/blurfl.c
  279.  
  280.             without the leading slash, -p4 gives
  281.  
  282.                  blurfl/blurfl.c
  283.  
  284.             and  not  specifying  -p  at  all  just   gives   you
  285.             "blurfl.c",  unless  all  of  the  directories in the
  286.             leading path  (u/howard/src/blurfl)  exist  and  that
  287.             path  is  relative,  in which case you get the entire
  288.             pathname unmodified.  Whatever you  end  up  with  is
  289.             looked  for  either  in the current directory, or the
  290.             directory specified by the -d option.
  291.  
  292.        -r file, --reject-file=file
  293.             causes file to be  interpreted  as  the  reject  file
  294.             name.
  295.  
  296.        -R, --reverse
  297.             tells  patch that this patch was created with the old
  298.             and new files swapped.  (Yes, I'm  afraid  that  does
  299.             happen  occasionally, human nature being what it is.)
  300.             Patch will attempt to swap each  hunk  around  before
  301.             applying  it.   Rejects  will come out in the swapped
  302.             format.  The -R option will not  work  with  ed  diff
  303.             scripts  because  there  is too little information to
  304.             reconstruct the reverse operation.
  305.  
  306.             If the first  hunk  of  a  patch  fails,  patch  will
  307.             reverse  the  hunk  to  see if it can be applied that
  308.             way.  If it can, you will be asked  if  you  want  to
  309.             have  the -R option set.  If it can't, the patch will
  310.             continue to be applied normally.  (Note: this  method
  311.             cannot detect a reversed patch if it is a normal diff
  312.             and if the first command is an append (i.e. it should
  313.             have been a delete) since appends always succeed, due
  314.             to the fact that a null context will match  anywhere.
  315.             Luckily, most patches add or change lines rather than
  316.             delete them, so most reversed normal diffs will begin
  317.  
  318.  
  319.  
  320.                               LOCAL                             5
  321.  
  322.  
  323.  
  324. PATCH(1)                                                 PATCH(1)
  325.  
  326.  
  327.             with  a  delete,  which  will  fail,  triggering  the
  328.             heuristic.)
  329.  
  330.        -s, --silent, --quiet
  331.             makes patch do its work  silently,  unless  an  error
  332.             occurs.
  333.  
  334.        -S, --skip
  335.             causes  patch  to  ignore  this  patch from the patch
  336.             file, but continue on looking for the next  patch  in
  337.             the file.  Thus
  338.  
  339.                  patch -S + -S + <patchfile
  340.  
  341.             will ignore the first and second of three patches.
  342.  
  343.        -u, --unified
  344.             forces patch to interpret the patch file as a unified
  345.             context diff (a unidiff).
  346.  
  347.        -v, --version
  348.             causes patch to print out  its  revision  header  and
  349.             patch level.
  350.  
  351.        -V method, --version--control=method
  352.             causes  method to be interpreted as a method for cre­
  353.             ating backup file names.  The type  of  backups  made
  354.             can  also be given in the VERSION_CONTROL environment
  355.             variable, which is overridden by this option.  The -B
  356.             option  overrides  this option, causing the prefix to
  357.             always be used for making  backup  file  names.   The
  358.             value of the VERSION_CONTROL environment variable and
  359.             the argument to the -V option are like the GNU  Emacs
  360.             `version-control'  variable; they also recognize syn­
  361.             onyms that are more descriptive.   The  valid  values
  362.             are (unique abbreviations are accepted):
  363.  
  364.             `t' or `numbered'
  365.                    Always make numbered backups.
  366.  
  367.             `nil' or `existing'
  368.                    Make  numbered  backups  of files that already
  369.                    have them, simple backups of the others.  This
  370.                    is the default.
  371.  
  372.             `never' or `simple'
  373.                    Always make simple backups.
  374.  
  375.        -x number, --debug=number
  376.             sets  internal  debugging  flags,  and is of interest
  377.             only to patch patchers.
  378.  
  379. AUTHOR
  380.        Larry Wall <lwall@netlabs.com>
  381.  
  382.  
  383.  
  384.                               LOCAL                             6
  385.  
  386.  
  387.  
  388. PATCH(1)                                                 PATCH(1)
  389.  
  390.  
  391.        with many other contributors.
  392.  
  393. ENVIRONMENT
  394.        TMPDIR Directory to put temporary  files  in;  default  is
  395.               /tmp.
  396.  
  397.        SIMPLE_BACKUP_SUFFIX
  398.               Extension  to  use for backup file names instead of
  399.               ".orig" or "~".
  400.  
  401.        VERSION_CONTROL
  402.               Selects when numbered backup files are made.
  403.  
  404. FILES
  405.        $TMPDIR/patch*
  406.  
  407. SEE ALSO
  408.        diff(1)
  409.  
  410. NOTES FOR PATCH SENDERS
  411.        There are several things you should bear in  mind  if  you
  412.        are  going to be sending out patches.  First, you can save
  413.        people a lot of grief by keeping a patchlevel.h file which
  414.        is  patched to increment the patch level as the first diff
  415.        in the patch file you send out.  If you put a Prereq: line
  416.        in  with the patch, it won't let them apply patches out of
  417.        order without some  warning.   Second,  make  sure  you've
  418.        specified  the  file names right, either in a context diff
  419.        header, or with an Index: line.  If you are patching some­
  420.        thing in a subdirectory, be sure to tell the patch user to
  421.        specify a -p option as needed.  Third, you  can  create  a
  422.        file  by  sending  out a diff that compares a null file to
  423.        the file you want to create.  This will only work  if  the
  424.        file  you want to create doesn't exist already in the tar­
  425.        get directory.  Fourth, take care not to send out reversed
  426.        patches, since it makes people wonder whether they already
  427.        applied the patch.  Fifth, while you may be  able  to  get
  428.        away  with  putting 582 diff listings into one file, it is
  429.        probably wiser to  group  related  patches  into  separate
  430.        files in case something goes haywire.
  431.  
  432. DIAGNOSTICS
  433.        Too many to list here, but generally indicative that patch
  434.        couldn't parse your patch file.
  435.  
  436.        The message "Hmm..." indicates that there  is  unprocessed
  437.        text  in  the  patch  file and that patch is attempting to
  438.        intuit whether there is a patch in that text and,  if  so,
  439.        what kind of patch it is.
  440.  
  441.        Patch will exit with a non-zero status if any reject files
  442.        were created.  When applying a set of patches in a loop it
  443.        behooves  you to check this exit status so you don't apply
  444.        a later patch to a partially patched file.
  445.  
  446.  
  447.  
  448.                               LOCAL                             7
  449.  
  450.  
  451.  
  452. PATCH(1)                                                 PATCH(1)
  453.  
  454.  
  455. CAVEATS
  456.        Patch cannot tell if the line numbers are  off  in  an  ed
  457.        script,  and  can only detect bad line numbers in a normal
  458.        diff when it finds a "change" or a  "delete"  command.   A
  459.        context  diff  using fuzz factor 3 may have the same prob­
  460.        lem.  Until a suitable interactive interface is added, you
  461.        should probably do a context diff in these cases to see if
  462.        the changes made  sense.   Of  course,  compiling  without
  463.        errors  is a pretty good indication that the patch worked,
  464.        but not always.
  465.  
  466.        Patch usually produces the correct results, even  when  it
  467.        has  to  do  a  lot of guessing.  However, the results are
  468.        guaranteed to be correct only when the patch is applied to
  469.        exactly  the  same  version of the file that the patch was
  470.        generated from.
  471.  
  472. BUGS
  473.        Could  be  smarter  about  partial  matches,   excessively
  474.        deviant  offsets  and swapped code, but that would take an
  475.        extra pass.
  476.  
  477.        If code has been duplicated (for instance with #ifdef OLD­
  478.        CODE  ... #else ...  #endif), patch is incapable of patch­
  479.        ing both versions, and, if it works at  all,  will  likely
  480.        patch  the  wrong  one,  and tell you that it succeeded to
  481.        boot.
  482.  
  483.        If you apply a patch you've already  applied,  patch  will
  484.        think  it  is  a reversed patch, and offer to un-apply the
  485.        patch.  This could be construed as a feature.
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.                               LOCAL                             8
  513.